home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Diamond Collection / The Diamond Collection (Software Vault)(Digital Impact).ISO / cdr13 / aurora2c.zip / REGEXP.DOX < prev    next >
Text File  |  1995-04-07  |  12KB  |  297 lines
  1.  
  2.  
  3.   Regular Expression Searching
  4.   ────────────────────────────
  5.   The Regular Expression search option 'x' allows you to specify complex
  6.   search patterns when searching through buffers or strings. Option 'x'
  7.   can be specified in both end-user search prompts and macro language
  8.   searching functions (such as 'find' and 'replace').
  9.  
  10.   Regular expression search patterns are created by combining normal
  11.   characters with regular expression 'operator' characters in the search
  12.   string. These operators take on a special meaning when the search
  13.   option 'x' is specified.
  14.  
  15.   Each operator matches a pattern. There are operators which allow you
  16.   to anchor searches to the beginning or end of a line, match any
  17.   character, match a class of characters or its complement, optionally
  18.   match a pattern, match one of several patterns, match repeating
  19.   patterns, and match groups of patterns.
  20.  
  21.   A rich set of regular expression operators are provided. The following
  22.   table lists and describes each of the operators:
  23.  
  24.  
  25.   Operator  Description
  26.   ────────  ───────────
  27.  
  28.   ^         Matches the beginning of a line. If the search is confined
  29.             to a marked block with search option 'b', then this operator
  30.             matches the beginning column of the mark. For example:
  31.  
  32.               ^         // matches the beginning of a line
  33.               ^a        // matches 'a' at the beginning of a line
  34.               ^apples   // matches 'apples' at the beginning of a line
  35.  
  36.   $         Matches the end of a line. If the search is confined to a
  37.             marked block with search option 'b', then this operator
  38.             matches the ending column of the mark or line. For example:
  39.  
  40.               $         // matches the end of a line
  41.               o$        // matches 'o' at the end of a line
  42.               oranges$  // matches 'oranges' at the end of a line
  43.  
  44.   .         Matches any character. For example:
  45.  
  46.               .         // matches any single character
  47.               ..        // matches any two consecutive characters
  48.               t.o       // matches 'two' or 'too', but not
  49.                         //   'toe' or 'true'
  50.  
  51.   [ ]       Specifies a 'class' of characters that a single character
  52.             can match. For example:
  53.  
  54.               [ab]      // matches 'a' or 'b'
  55.               [abc12!]  // matches 'a', 'b', 'c', '1', '2', or '!'
  56.               [AaZz]    // matches 'A', 'a', 'Z', or 'z'
  57.  
  58.             Note that the character class is always case-sensitive, even
  59.             when the 'ignore case' search option 'i' is specified.
  60.  
  61.   [ - ]     Specifies a range of characters to match when used between
  62.             characters in a class. Note that '-' is treated as a normal
  63.             character if used as the first or last character of the
  64.             class, or if used outside the class. For example:
  65.  
  66.               [a-z]        // matches characters 'a' through 'z'
  67.               [-+0-9]      // matches characters '0' through '0' and
  68.                            //   '-' and '+'
  69.               [a-zA-Z0-9]  // matches any alphanumeric character
  70.  
  71.   [~ ]      Specifies the complement of a character class against which
  72.             to match a character. The '~' operator is only meaningful
  73.             when used as the first character after the '[' bracket,
  74.             otherwise it is treated as any other normal character. For
  75.             example:
  76.  
  77.               [~ab]        // match any characters other than 'a' or 'b'
  78.               [~12~]       // match any characters other than
  79.                            //   '1', '2', or '~'
  80.               [~0-9]       // match any non-numeric character
  81.  
  82.   ?         Optionally matches the preceding pattern. For example:
  83.  
  84.               thes?e       // matches 'thee' or 'these'
  85.               the[sm]?e    // matches 'thee', 'these', or 'theme'
  86.  
  87.   |         This is the alternation ('or') operator. It matches the
  88.             preceding or the following pattern. For example:
  89.  
  90.               the|in       // matches 'then' or 'thin'
  91.                            //   (but not 'the' or 'in)
  92.               thes|me      // matches 'these' or 'theme'
  93.  
  94.             Multiple '|' operators can be chained together. The 'or-ed'
  95.             patterns are searched in the order in which they are listed.
  96.             For example:
  97.  
  98.               thes|m|r| |e
  99.                 // matches 'these', 'theme', 'there', or 'the e'
  100.               {apples}|{oranges}|{bananas}
  101.                 // matches 'apples', 'oranges', or 'bananas' (see below
  102.                 // for a description the grouping operator '{}')
  103.  
  104.   *         Matches zero or more occurrences of the preceding pattern,
  105.             matching as few occurrences as possible (minimum closure).
  106.             For example:
  107.  
  108.               fo*bar
  109.                 // matches 'fbar', 'fobar', 'foobar', 'fooobar', etc.
  110.  
  111.               apples.*oranges
  112.                 // matches any string starting with 'apples' and ending
  113.                 // with 'oranges':
  114.  
  115.             'Minimum closure' means that the shortest possible string is
  116.             matched. For example, if the search pattern is 'ab*b' and
  117.             string to be searched is 'abbbbbbb', then 'ab' will be
  118.             matched. Thus, the '*'and '+' operators are seldom used at
  119.             the end of a search string).
  120.  
  121.   +         Matches one or more occurrences of the preceding pattern,
  122.             matching as few occurrences as possible (minimum closure).
  123.             For example:
  124.  
  125.               fo+bar
  126.                 // matches 'fobar', 'foobar', 'fooobar', etc.
  127.               apples +oranges
  128.                 // matches any string starting with 'apples', followed
  129.                 // by one or more spaces, and ending with 'oranges':
  130.  
  131.   @         Matches zero or more occurrences of the preceding pattern,
  132.             matching as many occurrences as possible (maximum closure).
  133.             For example:
  134.  
  135.               a.@z
  136.                 // matches a string starting with 'a' and ending with
  137.                 // 'z', for the longest possible string
  138.               '.@'
  139.                 // matches a single-quoted string for the longest
  140.                 // possible string
  141.  
  142.             'Maximum closure' means that the longest possible string is
  143.             matched. For example, if the search pattern is "ab@b", and
  144.             the string to be searched is 'abbbbbbb', then 'abbbbbbb'
  145.             will be matched.
  146.  
  147.   #         Matches one or more occurrences of the preceding pattern,
  148.             matching as many occurrences as possible (maximum closure).
  149.             For example:
  150.  
  151.               [a-zA-Z]#
  152.                 // matches the first occurrence of one or more
  153.                 // alphabetic characters, for the longest string
  154.                 // possible
  155.               string2#
  156.                 // matches 'string2', 'string22', 'string222', etc.
  157.                 // (matching the longest possible string)
  158.  
  159.   { }       Groups characters or other patterns together as one pattern,
  160.             so that regular expression operators can act on the entire
  161.             pattern. For example:
  162.  
  163.               {apples}|{oranges}
  164.                 // matches 'apples' or 'oranges'
  165.               another{ fine}? mess
  166.                 // matches 'another mess' or 'another fine mess'
  167.               {ab}#
  168.                 // matches 'ab', 'abab', 'ababab', etc.
  169.               {{ab}|{xy}}#
  170.                 // matches 'ab', 'xy', 'abab', 'abxy', 'xyab', 'abxyab',
  171.                 // etc.
  172.  
  173.             The '{}' operator also identifies or 'tags' patterns for
  174.             replacement (see below).
  175.  
  176.   \         Indicates that the next character is to taken literally and
  177.             not used as a regular expression operator. For example:
  178.  
  179.               apples\++oranges
  180.                 // matches 'apples+oranges', 'apples++oranges', etc.
  181.               whats all this then\?
  182.                 // matches "whats all this then?"
  183.               c:\\file\.?txt
  184.                 // matches 'c:\filetxt' or 'c:\file.txt'
  185.  
  186.             The '\' operator can also be used to match specific
  187.             characters:
  188.  
  189.               \a    matches the alert (beep) character (ASCII 7)
  190.               \b    matches the backspace character (ASCII 8)
  191.               \f    matches the formfeed character (ASCII 12)
  192.               \n    matches the newline (linefeed) character (ASCII 10)
  193.               \r    matches the return character (ASCII 13)
  194.               \t    matches the tab character (ASCII 9)
  195.               \v    matches the vertical tab character (ASCII 11)
  196.               \xHH  matches the hexadecimal character 'HH'
  197.  
  198.             For example:
  199.  
  200.               \t\t
  201.                 // matches two tab characters
  202.               \x00|\r
  203.                 // matches a binary zero or a return character
  204.                 // (ASCII 13)
  205.  
  206.             The '\' operator is also used within a replacement pattern
  207.             to reference a pattern which was tagged with the grouping
  208.             '{}' operator (see below).
  209.  
  210.  
  211.   The following are a few additional examples of regular expression
  212.   search patterns:
  213.  
  214.     ^ *$    // matches blank lines
  215.     ^.*$    // matches all the characters on any line
  216.     ^.+$    // matches all the characters on any non-blank line
  217.  
  218.     {if}|{else}|{for}|{while}|{switch}|{return}|{break}
  219.       // matches a few 'C' language keywords
  220.  
  221.     [a-zA-Z0-9_]#
  222.       // matches identifiers in most languages
  223.  
  224.     ^ *{function}|{key}.*$
  225.       // matches AML function headers
  226.  
  227.     [a-zA-Z0-9_]# *= *[0-9]#
  228.       // matches statements of the form: variable = number
  229.  
  230.  
  231.   Regular Expression Replacement Patterns
  232.   ───────────────────────────────────────
  233.   A pattern which was 'tagged' by the grouping operator '{}' in the
  234.   search string of a regular expression search-and-replace operation can
  235.   be referenced in the replacement string by using the '\' replacement
  236.   operator. Tagged patterns are numbered from 1 to 9 based on the
  237.   leftmost '{' symbol in the search string. The pattern number is
  238.   specified after the '\' character in the replacement string. For
  239.   example:
  240.  
  241.     search string:    "{.*}"         // changes double-quoted strings
  242.     replace string:   '\1'           // to single-quoted strings
  243.  
  244.     search string:    {[a-zA-Z]#} +{[a-zA-Z]#}
  245.     replace string:   \2 and \1
  246.  
  247.   The example above reverses two adjacent alphabetic words and places
  248.   the word 'and' between them.
  249.  
  250.  
  251.   Specifying '\0' in the replacement string references the entire search
  252.   pattern. For example:
  253.  
  254.     search string:    ^.+$           // encloses non-blank lines
  255.     replace string:   (\0)           // in parentheses
  256.  
  257.     search string:    [a-zA-Z0-9]#   // duplicates alphanumeric
  258.     replace string:   \0\0           // identifiers
  259.  
  260.  
  261.   To enter the '\' character in a replacement string, enter it twice.
  262.   For example:
  263.  
  264.     search string:    ^              // insert '\\' at the beginning
  265.     replace string:   \\\\           // of each line
  266.  
  267.  
  268.  
  269.   Summary of Regular Expression Operators
  270.   ───────────────────────────────────────
  271.  
  272.   Operator  Description
  273.   ────────  ───────────
  274.   ^         match the beginning of a line
  275.   $         match the end of a line
  276.   .         match any character
  277.   [ ]       specify a characters class
  278.   [ - ]     specify a range of characters
  279.   [~ ]      specify the complement of a character class
  280.   ?         optionally match the preceding pattern
  281.   |         the alternation ('or') operator
  282.   *         match zero or more of the preceding pattern (min closure)
  283.   +         match one or more of the preceding pattern (min closure)
  284.   @         match zero or more of the preceding pattern (max closure)
  285.   #         match one or more of the preceding pattern (max closure)
  286.   { }       define a group or tag a pattern
  287.   \         literal operator, or reference a tagged pattern
  288.   \a        match the alert or beep character (ASCII 7)
  289.   \b        match the backspace character (ASCII 8)
  290.   \f        match the formfeed character (ASCII 12)
  291.   \n        match the newline or linefeed character (ASCII 10)
  292.   \r        match the return character (ASCII 13)
  293.   \t        match the tab character (ASCII 9)
  294.   \v        match the vertical tab character (ASCII 11)
  295.   \xHH      match the hexadecimal character 'HH'
  296.  
  297.